Skip to main content

Iglu Builder

GitHub

Introduction​

The Iglu Builder is the component of the Iglu Project that can build nix derivations and push it to cachix compatible nix caches like our Iglu Cache.

Websocket​

This is the documentation to the /api/v1/build Websocket

info

This Endpoint accepts only one connection simultaneously!

Requests​

Start a build job​

To start a build job you have to send a json with this schema:

Details
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "git": {
      "type": "object",
      "properties": {
        "repository": { "type": "string" },
        "branch": { "type": "string" },
        "gitUsername": { "type": "string" },
        "gitKey": { "type": "string" },
        "requiresAuth": { "type": "boolean" },
        "noClone": { "type": "boolean" }
      },
      "required": ["noClone"],
      "additionalProperties": false
    },
    "buildOptions": {
      "type": "object",
      "properties": {
        "cores": { "type": "number" },
        "maxJobs": { "type": "number" },
        "keep_going": { "type": "boolean" },
        "extraArgs": { "type": "string" },
        "substituters": {
          "type": "array",
          "items": { "type": "string" }
        },
        "trustedPublicKeys": {
          "type": "array",
          "items": { "type": "string" }
        },
        "command": { "type": "string" },
        "cachix": {
          "type": "object",
          "properties": {
            "push": { "type": "boolean" },
            "target": { "type": "string" },
            "apiKey": { "type": "string" },
            "signingKey": { "type": "string" }
          },
          "required": ["push"],
          "additionalProperties": false
        }
      },
      "required": ["command", "cachix"],
      "additionalProperties": false
    }
  },
  "required": ["git", "buildOptions"],
  "additionalProperties": true
}

For example:

Details

This will clone https://github.com/iglu-sh/builder and build the derivation iglu-builder. This derivation will be pushed to https://cache.example.com/default

{
    "git": {
        "noClone": false
        "repository": "https://github.com/iglu-sh/builder"
    },
    "buildOptions": {
        "command": "nix build .#iglu-builder",
        "cachix": {
            "push": true,
            "target": "http://cache.example.com/default",
            "apiKey": "0197178f-b4f3-7000-acai-fec951e85504",
            "signingKey": "SgykdnDTu9iRkZZQhaif81C22fUERBiagMvD2oeMBUaE/4yAPYL3PJHinFVWkuvwUwp1MhSSKQ7pVlO4FGGCSQ=="
        }
    }
}

Responses​

Every response has this schema:

Details
schema
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "msg": { "type": "string" },
        "error": { "type": "string" },
        "stdout": { "type": "string" },
        "jobStatus": {
            "type": "string",
            "enum": ["failed", "success", "starting", "running"]
        },
        "childExitCode": { "type": "number" }
    }
    "required": [ "jobStatus" ],
    "additionalProperties": false
}

Too many connections​

Details
{
    "error": "A build job is already running.",
    "jobStatus": "running"
}

Start building​

Details
{
    "msg": "Start Building",
    "jobStatus": "starting"
}

Output of build job​

Details
{
    "stdout": "SOME_OUTPUT",
    "jobStatus": "running"
}

Invalid command​

Details
{
    "error": "Invalid command: 'YOUR_COMMAND'",
    "buildExitCode": 2,
    "jobStatus": "failed"
}

Build failed​

Details
{
    "error": "Something went wrong while building. Builder exited with error code CHILD_EXIT_CODE",
    "buildExitCode": CHILD_EXIT_CODE,
    "jobStatus": "failed"
}

Build succeeded​

Details
{
    "msg": "Build was successfull",
    "buildExitCode": 0,
    "jobStatus": "success"
}

Invalid JSON schema​

Details
{
    "error": "JSON schema is not valid.",
    "jobStatus": "failed"
}

Invalid JSON​

Details
{
    "error": "Not a valid JSON",
    "jobStatus": "failed"
}